<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>assertions &mdash; The Logtalk Handbook v3.93.0-b01 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
      <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=396eccfe" />

  
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script src="../_static/jquery.js?v=5d32c60e"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
        <script src="../_static/documentation_options.js?v=c8100655"></script>
        <script src="../_static/doctools.js?v=9a2dae69"></script>
        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/js/theme.js"></script>
    <!-- begin favicon -->
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
    <link rel="manifest" href="/site.webmanifest" />
    <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#5bbad5" />
    <meta name="msapplication-TileColor" content="#355b95" />
    <meta name="theme-color" content="#ffffff" />
    <!-- end favicon -->
    
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="code_metrics" href="code_metrics.html" />
    <link rel="prev" title="asdf" href="asdf.html" />
   
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            The Logtalk Handbook
              <img src="../_static/logtalk.gif" class="logo" alt="Logo"/>
          </a>
              <div class="version">
                3.93.0
              </div>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
    
              <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../userman/index.html">User Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../refman/index.html">Reference Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">FAQ</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Developer Tools</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="asdf.html"><code class="docutils literal notranslate"><span class="pre">asdf</span></code></a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#"><code class="docutils literal notranslate"><span class="pre">assertions</span></code></a><ul>
<li class="toctree-l3"><a class="reference internal" href="#api-documentation">API documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="#loading">Loading</a></li>
<li class="toctree-l3"><a class="reference internal" href="#testing">Testing</a></li>
<li class="toctree-l3"><a class="reference internal" href="#adding-assertions-to-your-source-code">Adding assertions to your source code</a></li>
<li class="toctree-l3"><a class="reference internal" href="#automatically-adding-file-and-line-context-information-to-assertions">Automatically adding file and line context information to assertions</a></li>
<li class="toctree-l3"><a class="reference internal" href="#suppressing-assertion-calls-from-source-code">Suppressing assertion calls from source code</a></li>
<li class="toctree-l3"><a class="reference internal" href="#redirecting-assertion-failure-messages">Redirecting assertion failure messages</a></li>
<li class="toctree-l3"><a class="reference internal" href="#converting-assertion-failures-into-errors">Converting assertion failures into errors</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="code_metrics.html"><code class="docutils literal notranslate"><span class="pre">code_metrics</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="dead_code_scanner.html"><code class="docutils literal notranslate"><span class="pre">dead_code_scanner</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="debug_messages.html"><code class="docutils literal notranslate"><span class="pre">debug_messages</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="debugger.html"><code class="docutils literal notranslate"><span class="pre">debugger</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="diagrams.html"><code class="docutils literal notranslate"><span class="pre">diagrams</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="doclet.html"><code class="docutils literal notranslate"><span class="pre">doclet</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="help.html"><code class="docutils literal notranslate"><span class="pre">help</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="issue_creator.html"><code class="docutils literal notranslate"><span class="pre">issue_creator</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="lgtdoc.html"><code class="docutils literal notranslate"><span class="pre">lgtdoc</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="lgtunit.html"><code class="docutils literal notranslate"><span class="pre">lgtunit</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="linter.html"><code class="docutils literal notranslate"><span class="pre">linter</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="make.html"><code class="docutils literal notranslate"><span class="pre">make</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="packs.html"><code class="docutils literal notranslate"><span class="pre">packs</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="ports_profiler.html"><code class="docutils literal notranslate"><span class="pre">ports_profiler</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="profiler.html"><code class="docutils literal notranslate"><span class="pre">profiler</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="tutor.html"><code class="docutils literal notranslate"><span class="pre">tutor</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="wrapper.html"><code class="docutils literal notranslate"><span class="pre">wrapper</span></code></a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../libraries/index.html">Libraries</a></li>
<li class="toctree-l1"><a class="reference internal" href="../ports/index.html">Ports</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributions/index.html">Contributions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../bibliography.html">Bibliography</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>

    <p class="caption"><span class="caption-text">External Contents</span></p>
    <ul>
    <li class="toctree-l1"><a class="reference internal" href="../../apis/index.html">APIs</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://logtalk.org">Logtalk website</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://github.com/LogtalkDotOrg/logtalk3">GitHub repo</a></li>
    </ul>
  
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">The Logtalk Handbook</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">Developer Tools</a></li>
      <li class="breadcrumb-item active"><code class="docutils literal notranslate"><span class="pre">assertions</span></code></li>
      <li class="wy-breadcrumbs-aside">
              <a href="https://github.com/LogtalkDotOrg/logtalk3/blob/master/docs/handbook/sources/devtools/assertions.rst" class="fa fa-github"> Edit on GitHub</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="assertions">
<span id="library-assertions"></span><h1><code class="docutils literal notranslate"><span class="pre">assertions</span></code><a class="headerlink" href="#assertions" title="Link to this heading"></a></h1>
<p>The <code class="docutils literal notranslate"><span class="pre">assertions.lgt</span></code> file contains definitions for two
meta-predicates, <code class="docutils literal notranslate"><span class="pre">assertion/1-2</span></code>, which allows the use of assertions
on your source code to print warning and error messages (using the
message printing mechanism). The <code class="docutils literal notranslate"><span class="pre">assertions_messages.lgt</span></code> file
defines the default message translations generated when assertions
succeed, fail, or throw an exception.</p>
<section id="api-documentation">
<h2>API documentation<a class="headerlink" href="#api-documentation" title="Link to this heading"></a></h2>
<p>This tool API documentation is available at:</p>
<p><a class="reference external" href="../../apis/library_index.html#assertions">../../apis/library_index.html#assertions</a></p>
</section>
<section id="loading">
<h2>Loading<a class="headerlink" href="#loading" title="Link to this heading"></a></h2>
<p>This tool can be loaded using the query:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> <span class="k">logtalk_load</span>(assertions(loader)).
</pre></div>
</div>
</section>
<section id="testing">
<h2>Testing<a class="headerlink" href="#testing" title="Link to this heading"></a></h2>
<p>To test this tool, load the <code class="docutils literal notranslate"><span class="pre">tester.lgt</span></code> file:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> <span class="k">logtalk_load</span>(assertions(tester)).
</pre></div>
</div>
</section>
<section id="adding-assertions-to-your-source-code">
<h2>Adding assertions to your source code<a class="headerlink" href="#adding-assertions-to-your-source-code" title="Link to this heading"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">assertion/1</span></code> predicate takes a goal as argument. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>foo(<span class="nv">L</span>) <span class="o">:-</span>
    assertions<span class="o">::</span>assertion(non_empty_list(<span class="nv">L</span>)),
    ...
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">assertion/2</span></code> predicate takes as arguments a term for passing
context information and a goal. Using again a unit test as an example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>foo(<span class="nv">L</span>) <span class="o">:-</span>
    assertions<span class="o">::</span>assertion(foo_list_alerts, non_empty_list(<span class="nv">L</span>)),
    ...
</pre></div>
</div>
<p>When using a large number of assertions, you can use a lighter syntax by
adding a <code class="docutils literal notranslate"><span class="pre">uses/2</span></code> directive. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">uses</span>(assertions, [assertion<span class="o">/</span><span class="m">1</span>, assertion<span class="o">/</span><span class="m">2</span>]).
</pre></div>
</div>
</section>
<section id="automatically-adding-file-and-line-context-information-to-assertions">
<h2>Automatically adding file and line context information to assertions<a class="headerlink" href="#automatically-adding-file-and-line-context-information-to-assertions" title="Link to this heading"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">assertions/1</span></code> parametric object can be used as a hook object to
automatically add file and line context information, represented by the
term <code class="docutils literal notranslate"><span class="pre">file_lines(File,</span> <span class="pre">BeginLine-EndLine)</span></code>, to calls to the
<code class="docutils literal notranslate"><span class="pre">assertion/1</span></code> predicate by goal-expanding it to calls to the
<code class="docutils literal notranslate"><span class="pre">assertion/2</span></code> predicate (the expansion assumes that a <code class="docutils literal notranslate"><span class="pre">uses/2</span></code>
directive is being used in the code that will be expanded to direct
<code class="docutils literal notranslate"><span class="pre">assertion/1</span></code> calls to the <code class="docutils literal notranslate"><span class="pre">assertions</span></code> object). For example,
assuming the file using assertions is named <code class="docutils literal notranslate"><span class="pre">source</span></code>, it would be
compiled and loaded using the call:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="k">logtalk_load</span>(source, [hook(assertions(debug))])
</pre></div>
</div>
</section>
<section id="suppressing-assertion-calls-from-source-code">
<h2>Suppressing assertion calls from source code<a class="headerlink" href="#suppressing-assertion-calls-from-source-code" title="Link to this heading"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">assertions/1</span></code> parametric object can be used as a hook object to
suppress calls to the <code class="docutils literal notranslate"><span class="pre">assertion/1-2</span></code> predicates using goal-expansion
(the expansion assumes <code class="docutils literal notranslate"><span class="pre">assertions::assertion/1-2</span></code> messages). For
example, assuming the file using assertions is named <code class="docutils literal notranslate"><span class="pre">source</span></code>, it
would be compiled and loaded using the call:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="k">logtalk_load</span>(source, [hook(assertions(production))])
</pre></div>
</div>
</section>
<section id="redirecting-assertion-failure-messages">
<h2>Redirecting assertion failure messages<a class="headerlink" href="#redirecting-assertion-failure-messages" title="Link to this heading"></a></h2>
<p>By default, assertion failures and errors are printed to the standard
output stream. These messages, however, can be intercepted by defining
the <code class="docutils literal notranslate"><span class="pre">logtalk::message_hook/4</span></code> multifile predicate. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">category</span>(redirect_assertions_messages).

<span class="p">    :- </span><span class="k">multifile</span>(logtalk<span class="o">::</span>message_hook<span class="o">/</span><span class="m">4</span>).
<span class="p">    :- </span><span class="k">dynamic</span>(logtalk<span class="o">::</span>message_hook<span class="o">/</span><span class="m">4</span>).

    logtalk<span class="o">::</span>message_hook(<span class="nv">Message</span>, error, assertions, <span class="nv">_</span>) <span class="o">:-</span>
        <span class="k">writeq</span>(my_log_file, <span class="nv">Message</span>), <span class="k">write</span>(my_log_file, <span class="s">&#39;.</span><span class="se">\n</span><span class="s">&#39;</span>).

<span class="p">:- </span><span class="k">end_category</span>.
</pre></div>
</div>
</section>
<section id="converting-assertion-failures-into-errors">
<h2>Converting assertion failures into errors<a class="headerlink" href="#converting-assertion-failures-into-errors" title="Link to this heading"></a></h2>
<p>If you want an assertion failure to result in a failure or a runtime
error, you can intercept the assertion failure messages, optionally
still printing them, and throw an error. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">category</span>(assertions_failures_to_errors).

<span class="p">    :- </span><span class="k">multifile</span>(logtalk<span class="o">::</span>message_hook<span class="o">/</span><span class="m">4</span>).
<span class="p">    :- </span><span class="k">dynamic</span>(logtalk<span class="o">::</span>message_hook<span class="o">/</span><span class="m">4</span>).

    logtalk<span class="o">::</span>message_hook(<span class="nv">Message</span>, error, assertions, <span class="nv">Tokens</span>) <span class="o">:-</span>
        <span class="c">% uncomment the next two lines to also print the default message</span>
        <span class="c">% logtalk::message_prefix_stream(error, assertions, Prefix, Stream),</span>
        <span class="c">% logtalk::print_message_tokens(Stream, Prefix, Tokens),</span>
        <span class="k">throw</span>(error(<span class="nv">Message</span>, <span class="nv">_</span>)).

<span class="p">:- </span><span class="k">end_category</span>.
</pre></div>
</div>
<p>In alternative, if you want assertions to always trigger an exception,
use instead the <code class="docutils literal notranslate"><span class="pre">lgtunit</span></code> tool <code class="docutils literal notranslate"><span class="pre">assertions/1-2</span></code> public predicates.</p>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="asdf.html" class="btn btn-neutral float-left" title="asdf" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="code_metrics.html" class="btn btn-neutral float-right" title="code_metrics" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 1998-2025, Paulo Moura.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>